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FOREWORD 

This  document  is  a report  on  the  second  year's  accomplishments 
on  the  Calac  independent  research  task  entitled,  "Engineer  Oriented  Remote 
Computing"  (project  number  76011.102 ).  The  author  is  indebted  to  Dean  Saiki 
who  assisted  in  the  design  and  implementation  of  many  improvements  to  the 
production  system.  The  author  is  also  thankful  for  the  many  constructive 
suggestions  made  by  Howard  Weinberger  and  Thomas  R.  Jones  during  the 
course  of  this  task. 
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ABSTRACT 

The  usefulness  of  computers  in  solving  scientific  problems  is  a 
function  of  the  ease  with  which  users  can  communicate  with  existing  hard- 
ware and  software.  This  research  is  aimed  at  improving  such  man-computer 
communication.  Specifically,  a computer  system  has  been  designed  and 
partially  implemented  which  will  provide  a software  interface  between 
users,  possibly  inexperienced  in  computer  processing  techniques,  and 
available  programs  and  analysis  systems. 

This  system,  denoted  as  ASSIST  (A  Scientific  Software  Interface 
System  for  Terminal-users),  aids  users  in  accessing  and  utilizing  existing 
applications  software  from  remote  terminals.  The  system  provides  three 
basic  functions.  It  helps  users  find  programs  relevant  to  their  problems; 
it  assists  them  in  preparing  required  input  data;  and  it  aids  in  the 
actual  submittal  of  programs  and  data  for  computer  processing.  In  addi- 
tion, the  system  monitors  usage  of  the  facilities  and  provides  information 
for  aiding  management  in  making  decisions  for  ensuring  the  efficient  and 
proper  use  of  available  computer  resources. 

The  basic  approach  has  been  to  design  a language  which  pro- 
grammers can  use  to  describe  program  characteristics  (function,  input 
format,  submittal  requirements,  etc.).  ^ These  descriptions  can  then  be 
interactively  interpreted  by  ASSIST  to  aid  individuals  wishing  to  use  any 
available  program.  Thus,  the  user  has  a helpful  interface  system  he  can 
converse  with  while  he  is  trying  to  find,  prepare  input  for,  or  submit  a 
program. 
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'V 

INTRODUCTION 

Technological  advances  in  hardware  have  made  computers  practical 
and  economical  tools  for  ever  increasing  numbers  of  users.  More  and  more 
people  with  less  and  less  programming  experience  will  be  using  computers 
in  the  years  to  come.  No  longer  can  systems  be  designed  without  consid- 
eration of  these  ultimate  users.  The  effectiveness  of  future  systems 
will  be  measured  by  the  ease  with  which  man  can  communicate  with  them. 

Although  a great  quantity  of  problem  solving  software  is 
available  today,  most  is  usable  only  by  those  possessing  reasonable 
backgrounds  in  computing.  In  order  to  make  most  present  systems  and 
programs  useful  tools  for  the  non  computer  oriented  individual,  they  must 
either  be  redesigned,  or  some  communication's  interface  between  the  user 
and  the  existing  software  must  be  developed.  This  latter  approach,  if 
general  enough,  could  extend  many  existing  computing  capabilities  to  non 
programming  users  without  costly  redesign  of  applications  software. 

An  experimental  version  of  a system  aimed  at  providing  such  an 
interface  has  been  developed.  This  system,  denoted  ASSIST  (A  Scientific 
Software  Interface  System  for  Terminal-users),  was  designed  to  aid  users 
in  accessing  and  utilizing  existing  applications  software  from  remote 
terminals.  The  system  provides  three  basic  functions  for  the  user.  It 
helps  him  find  programs  relevant  to  his  problems;  it  assists  him  in 
preparing  input  for  selected  programs;  and  it  aids  in  the  actual  sub- 
mittal of  programs  and  data  for  computer  processing. 


This  report  discusses  the  progress  made  during  the  second  year 
(1976)  of  this  task.  The  preliminary  design  of  ASSIST  and  the  first 
year's  progress  are  contained  in  the  report,  "Engineer  Oriented  Remote 

Computing"  (I..R  27518). 
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SECTION  1.0 
OVERVIEW 

1.1  OBJECTIVE 

The  principal  objective  of  this  task  is  the  development  of  a 
user  oriented  system  to  aid  in  the  solving  of  problems  on  computers. 

This  system,  to  be  known  as  ASSIST  (A  Scientific  Software  Interface 
System  for  Terminal-users),  will  provide  an  interface  between  users, 
possibly  inexperienced  in  computer  processing  techniques,  and  the  exist- 
ing hardware  and  applications  software.  The  goals  of  this  system  are  to 
reduce  both  job  turnaround  time  and  costs  associated  with  the  use  of  ex- 
isting batch  oriented  software. 

1.2  EACKGROUND 

> 

Over  the  years  an  extensive  collection  of  application  programs 
and  systems  has  been  produced,  "aking  effective  use  of  this  software, 
however,  usually  requires  both  considerable  knowledge  of  individual  pro- 
grams and  familiarity  with  computer  processing  techniques  in  general. 

In  particular,  one  must  know  what  specific  programs  exist,  what  input 
data  is  required  for  each,  in  what  form  such  data  must  be  supplied,  and 
what  information  must  be  provided  to  the  computer  operating  system  to 
effect  the  actual  processing  of  programs  and  data. 

Non  programming  users  at  Calac  have  traditionally  depended  upon 
professional  programmers  as  their  interface  with  existing  software.  In 
the  computing  environment  prior  to  1975  (Figure  1),  it  was  the  professional 
programmer  who  directly  accessed  both  the  computer  and  the  library  of  ex- 
isting programs.  A non  programming  user,  with  a problem  to  solve,  would 

) 
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explain  it  to  some  programmer  who  would  perform  the  necessary  tasks  to 
prepare  a computer  acceptable  form  of  the  problem  (i.e.,  put  together 
program  and  data  with  required  system  control  information).  The  programmer 
would  then  accomplish  the  actual  computer  processing  and  return  the  results 
to  the  user.  This  mode  of  operation  had  obvious  inefficiencies  for  many 
kinds  of  problem  solving.  There  were  often  delays  in  processing  and  errors 
due  to  misunderstandings.  With  more  and  more  people  requiring  more  and 
more  computer  processing  there  was  clearly  a need  to  put  them  in  closer 
contact  with  the  computer. 

As  a consequence  of  this  conclusion,  a Direct  Computer  Access 
System,  DCAS,  was  established  which  logically  extended  the  computer  to 
allow  access  to  it  through  remote  terminals  (Figure  2).  Initially  DCAS 
existed  only  as  a subset  of  IBM's  Time  Sharing  Option  (TSO).  Although 
this  gave  a user  direct  access  to  the  computer,  it  did  not  improve  his 
access  to  the  library  of  programs.  This  research  deals  primarily  with 
the  task  of  extending  DCAS  to  improve  the  user's  ability  to  directly 
utilize  this  collection  of  existing  applications  software.  In  effect, 
the  goal  is  to  automate  the  interface  function  previously  provided  by 
the  programmer.  In  order  to  accomplish  this  the  programmer  must  be 
provided  with  some  means  for  transferring  his  "knowledge"  (or  information 
in  his  keeping)  regarding  the  use  of  specific  analysis  software  to  DCAS. 
ASSIST  is  that  augmentation  of  TSO  which  gives  DCAS  this  capability. 

1.3  SYSTEM  DESCRIPTION 

ASSIST  has  been  designed  to  bring  together  information  regarding 
existing  application  programs  and  potential  users  in  an  interactive  envi- 
onment  (see  Figure  3)»  For  each  program  to  be  made  available  through 
ASSIST,  certain  descriptive  information  will  be  provided  by  a programmer. 
This  information  includes  a general  program  description,  a complete  and 
and  precise  input  specification,  and  certain  job  control  information 
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necessary  for  running  the  program  on  the  computer.  The  user  will  then  be 
able  to  interact  with  various  components  of  ASSIST,  which  have  access  to 
this  programmer  supplied  information,  for  solving  some  problem.  If  he 
needs  information  regarding  the  availability  of  certain  software,  he  will 
access  the  Program  Selection  component.  This  will  tell  him  about  existing 
programs  in  a particular  category  he  selects.  Once  he  knows  which  program 
to  run  he  may  elect  to  access  the  Input  Preparation  component  to  assist  him 
in  preparing  his  data.  He  may  ask  to  be  prompted  for  every  quantity  needed 
or  merely  to  have  his  data  checked  for  completeness  and,  to  some  degree, 
correctness.  Finally  the  user  will  be  able  to  access  the  Program  Submittal 
component  which  will  automatically  create  all  necessary  job  control  in- 
formation and  submit  the  specified  program  and  data  for  execution. 

1.4  PROGRESS 

During  1975  a preliminary  design  of  ASSIST  was  completed.  The 
component  of  the  system  which  assists  users  in  submitting  programs  was 
developed  and  put  into  controlled  use  for  testing. 

In  1976  an  initial  production  version  of  ASSIST,  containing 
extensive  users  aids  for  program  submittal,  was  completed  and  put  into 
use.  Other  aids  were  implemented  and  several  more  were  designed  including 
software  to  help  users  in  preparing  program  input  data.  A detailed  account 
of  the  1976  progress  on  the  various  components  of  ASSIST  is  presented  in 
the  following  sections. 
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SECTION  2.0 
PROGRAM  SUBMITTAL 

2.1  OBJECTIVE 

The  purpose  of  this  component  of  ASSIST  is  to  simplify  the  task 
of  program  submittal  by  automatically  generating  the  necessary  job  control 
information  required  by  the  operating  system  for  program  execution.  The 
fundamental  concept  is  that  non  programming  users  should  not  be  required 
to  learn  the  details  of  interfacing  with  the  operating  system  in  order  to 
run  jobs  on  the  computer.  The  users  should  be  able  to  communicate  their 
needs  in  terms  meaningful  to  them  not  in  the  language  of  the  operating 
system.  For  example,  a user  desiring  plot  output  should  merely  have  to 
say,  "PLOTS"  or  respond  affirmatively  to  the  question,  "Do  you  want  the 
output  plotted?"  rather  than  have  to  know  how  to  appropriately  modify  the 
^ DD  (Data  Definition)  statement  of  the  associated  plot  file.  Such  capabil- 

ities could  be  of  great  benefit  to  the  experienced  programmer  as  well,  for 
even  with  a knowledge  of  JCL  (job  Control  Language),  it  might  be  'ar 
simpler  to  allow  ASSIST  to  automatically  generate  necessary  control  in- 
formation. Certainly  there  is  much  less  chance  of  error  for  either  the 
experienced  or  inexperienced  user  when  the  program  setup  and  control  in- 
formation are  produced  automatically. 

2.2  APPROACH 

The  approach  taken  in  this  research  for  assisting  users  in  pro- 
gram submittal  has  been  to  design  a language,  and  interpreter  for  it, 
which  can  be  used  by  programmers  for  expressing  the  information  necessary 
for  running  programs  on  the  computer.  This  language,  known  as  the  PS  I 
(Program  Setup  Instructions)  Macro  language,  is  an  augmented  job  control 
language  (JCL)  which  allows  construction  of  generalized  sets  of  JCL  for 
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the  IBM  operating  system.  The  interpreter  acts  as  a preprocessor  or 
macro  processor,  expanding  programs  written  in  this  language  into  complete 
and  valid  jobs  to  be  executed  on  the  computer. 

In  a typical  case,  a programmer  who  is  familiar  with  a particular 
program  and  the  JCL  required  to  run  it  will  develop  a generalized  set  of 
job  control  instructions  called  a PSI  macro.  This  PSI  macro  will  then  be 
placed  in  an  on-line  library  and,  hence,  will  be  available  to  all  users 
through  the  PSI  macro  processor  known  as  RUNPROG.  Once  a PSI  macro  has 
been  so  created  for  a given  program,  users  can  run  that  program  by  access- 
ing RUNPROG,  without  regard  to  any  JCL  concerns.  Furthermore,  changes 
that  may  be  required  in  the  JCL  due  to  program  modifications,  system 
changes,  or  operational  considerations  can  be  usually  made  in  the  single 
version  of  the  generalized  JCL  in  the  PSI  macro  library  without  requiring 
any  change  on  the  part  of  the  users.  In  cases  where  programming  changes 
were  made,  all  users  will  automatically  get  access  to  the  latest  version 
of  the  program.  Thus,  tnis  component  of  ASSIST  can  help  not  only  the  user 
in  program  submittal,  but  the  programmer  in  program  maintenance. 

2.3  PROGRESS 

During  1975  a preliminary  version  of  the  program  submittal 
component  (RUNPROG)  was  developed  and  put  into  limited  production  use. 

This  version  contained  only  capabilities  for  substitution  of  parameter 
values,  obtaining  user  related  information,  simple  communication  with  the 
user,  and  submittal  of  the  complete  job  for  batch  processing.  During  1976 
the  capabilities  of  the  program  submittal  component  were  greatly  expanded. 
The  most  significant  of  these  are  described  below  and  a complete  descrip- 
tion of  the  current  capabilities  of  RUNPROG  is  given  in  Appendix  A,  "Guide 
to  Ur i ting  a PSI  Macro." 
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Conditional  Expansion 


The  first  major  capability  added  to  RUNPROG  was  conditional  ex- 
pansion. A preprocessor  statement  similar  to  the  IF  statement  of  PL/l 
was  implemented  within  the  PSI  macro  language.  With  the  "IF"  a JCL  state- 
ment or  group  of  statements  can  be  included  or  excluded  in  the  job  being 
built  based  upon  some  test.  These  IF  statements  can  be  nested  to  any 
depth. 


2.3.2 


Interactive  Communication 


Capabilities  were  implemented  to  allow  communication  with  the 
user  during  execution  of  the  PSI  macro.  A PUT  statement  allows  the 
writer  of  a PSI  macro  to  cause  a message  to  be  displayed  at  the  user's 
terminal,  and  a GET  statement  permits  the  reading  of  a line  of  information 
from  the  terminal.  Thus,  a macro  can  be  written  which  asks  the  user  to 
supply  some  information  and  then  reads  in  what  is  given. 


2.3.3 


Iter at ion 


A capability,  not  in  the  original  design  of  RUNPROG,  was  added 
which  allows  the  repeated  execution  of  a series  of  macro  statements.  The 
preprocessor  statement  used  for  this  purpose  is  the  "DO-WHILE"  and  is 
similar  to  the  same  construct  in  PL/l.  The  group  of  statements  to  be 
executed  may  include  any  number  of  JCL  or  preprocessor  statements.  These 
statements  immediately  follow  the  DO-MILE  statement  and  conclude  with  a 
preprocessor  END  statement.  When  execution  reaches  the  END  statement, 
control  is  transferred  back  to  the  corresponding  DO-WHILE.  Part  of  the 
DO-WHILE  is  a condition  test  just  as  in  the  IF  statement.  As  long  as  the 
condition  remains  true  the  group  of  statements  following  the  DO-WHILE  is 
executed  again.  Once  the  condition  fails,  control  is  transferred  to  the 
statement  following  the  associated  END  statement.  DO- WHILE'S  can  be  nested 
to  any  depth. 
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A capability  was  added  to  the  design  and  implemented  which 
allows  the  extraction  of  a substring  from  a given  string  of  characters. 
This  function,  called  SUBSTR,  operates  identically  with  the  corresponding 
PL/ I function.  Any  consecutive  string  of  characters  can  be  extracted  from 
a given  string  by  specifying  the  beginning  position  and  the  number  of 
characters  to  take. 


2.3.5 


Programmer  Aids 


Software  has  been  designed  and  implemented  to  aid  programmers  in 
adding,  modifying,  and  deleting  PSI  macros  from  the  on-line  library.  A 
complete  log  of  changes  to  PSI  macros  is  maintained  by  the  system.  This 
log  contains  the  time  and  date  of  the  action,  the  identification  of  the 
programmer  taking  the  action,  the  name  of  the  macro  involved,  and  the 
type  of  action  taken.  The  software  also  checks  the  user's  identification 
to  ensure  he  is  authorized  to  modify  the  macro  library. 


A capability  has  also  been  added  to  aid  programmers  in  testing 
newly  developed  PSI  macros.  This  feature,  called  TESTMAC,  operates  like 
RUNPROG  except  it  accesses  a macro  in  the  programmer's  library  and  directs 
a listing  of  the  job  built  back  to  the  terminal  rather  than  submitting  it 
to  the  computer  for  execution.  Thus,  the  programmer  can  watch  the  job 
being  built,  card  by  card,  and  discover  any  errors  as  they  occur. 


2.3.6 


Other  Features  under  Development 


The  original  design  of  RUNPROG  included  the  capability  to  in- 
voke one  PSI  macro  from  within  another  and  the  ability  to  copy  a data  set 
into  the  job  being  built.  These  capabilities  are  currently  under  develop- 
ment and  will  be  implemented  in  the  production  version  during  the  third 
quarter  of  1977. 
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Also  included  in  the  original  design  was  the  ability  to  place 
arbitrary  expressions  wherever  constants  are  allowed  within  preprocessor 
statements.  Although  this  capability  has  been  fully  developed,  the  core 
limitations  of  the  current  TSO  environment  in  which  RUNPROG  operates,  have 
made  its  installation  impossible. 


The  design  of  RUNE ROG  was  modified  to  include  as  a diagnostic 
aid  the  capability  to  get  a symbol  table  dump  (i.e.,  a listing  of  all 
macro  variables  and  their  current  values),  and  several  new  functions. 

In  order  to  compensate  for  the  lack  of  arithmetic  capability  of  RUNPROG, 
INCR  (increment)  and  DECR  (decrement)  functions  were  defined.  INCR  allows 
increasing  the  value  of  a quantity  by  some  given  amount  while  DECR  allows 
for  reduction  in  a similar  manner.  Three  other  functions  added  to  the 
design  were  INDEX,  LENGTH  and  CONCAT.  These  are  string  manipulation 
functions  which  correspond  exactly  with  similar  constructs  in  PL/l. 

INDEX  allows  the  determination  of  whether  one  string  is  a substring  of 
another  and,  if  so,  returns  the  position  at  which  the  substring  begins. 
LENGTH  returns  the  number  of  characters  in  a given  string,  and  CONCAT 
allows  the  concatenation  of  two  strings.  These  functions  are  scheduled 
for  implementation  during  the  second  quarter  of  1977. 


Other  extensions  of  RUNPROG  which  will  be  studied  in  1977  in- 
clude the  GO- TO  statement,  a dynamic  naming  or  array  facility,  and  the 
ability  to  do  indirect  addressing.  Also  during  1977,  effort  will  be 
directed  at  improving  the  responsiveness  of  RUNPROG. 
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SECTION  3.0 
INPUT  PREPARATION 


3.1  OBJECTIVE 

The  purpose  of  this  component  of  ASSIST  is  to  aid  the  user  in 
preparing  input  data  for  a program  he  has  chosen  to  run.  It  will  do 
three  things  for  the  user.  It  will  tell  him  what  input  quantities  are 
required  for  a given  program;  it  will  enable  him  to  provide  those  values 
in  a convenient  manner  (without  requiring  that  he  know  the  specific  data 
formats  required  by  the  program);  and  it  will  check  the  data  he  provides 
both  for  completeness  and  correctness.  Furthermore,  this  component  can 
be  used  interactively,  prompting  the  user  when  necessary  and  allowing 
him  to  correct  errors  as  they  are  discovered.  The  effect  of  this  com- 
ponent is  to  put  a user's  guide  to  a program  on-line  and  in  such  a way 
that  the  user  can  converse  with  it. 

3.2  APPROACH 

The  approach  taken  for  this  component  is  basically  the  same  as 
that  used  for  program  submittal  (i.e.,  RUNPROG).  In  particular  a language 
has  been  developed  which  allows  programmers  to  describe  program  input 
requirements.  Actually  this  language  is  just  an  extension  of  the  PS  I 
macro  language  since  the  fundamental  requirements  of  this  component  are 
identical  with  those  of  program  submittal.  Namely,  it  must  interact  with 
a user,  providing  some  information  and  obtaining  other  information,  and 
based  on  that,  construct  a data  set.  In  the  case  of  program  submittal, 
the  data  set  built  is  job  stream  input  while  in  the  case  of  input  pre- 
paration, it  is  a data  set  for  input  to  some  program.  These  differences 
in  no  way  effect  the  logical  operation  of  the  component  of  ASSIST  which 
interprets  programmer  written  descriptions  and  interacts  with  users. 
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All  that  is  required,  therefore,  to  be  able  to  provide  assistance  to  the 
user  in  input  generation  is  to  add  certain  constructs  to  the  existing 
macro  language.  In  particular,  constructs  are  needed  which  allow  the 
description  of  required  input  parameters,  including  types  and  ranges  of 
acceptable  values,  and  the  format  in  which  the  program  expects  them  to  be 
given. 

With  such  an  expanded  macro  language,  a programmer  can  describe 
the  input  requirements  for  any  program  in  such  a way  that  data  prepared 
for  that  program  can  be  automatically  checked  for  completeness  and  correct- 
ness, and,  if  desired,  the  input  can  be  prepared  in  an  interactive  mode. 

In  the  latter  case,  information  will  be  requested  of  the  user  through  an 
input  description  (ID)  macro  written  by  a programmer.  Normally,  this 
request  will  be  a list  of  input  parameters  for  which  the  user  must  supply 
values.  Additional  messages  can  be  displayed  to  the  user  at  the  discretion 
of  the  programmer  writing  the  ID  macro.  The  user  can  ask  for  a description 
) of  any  parameter  requested  and  the  values  he  supplies  will  be  checked  for 

proper  type  (e.g.,  character,  integer,  etc.)  and  limits  (e.g.,  0<X<10) 
according  to  information  specified  in  the  ID  macro.  The  user  will  be 
immediately  notified  of  any  errors  and  allowed  to  correct  them.  The  input 
values  will  then  be  formatted  as  required  by  the  program.  When  this  com- 
ponent is  used  just  to  check  a prepared  data  set,  the  data  set  must  be 
properly  formatted.  In  this  case,  a list  of  all  discovered  errors  will  be 
returned  to  the  user.  The  use  of  this  component  could  result  in  significant 
savings  of  computer  resources  by  helping  users  to  prepare  program  input  data 
which  are  correct  the  first  time. 

3.3  PROGRESS 

A software  specification  for  the  extended  macro  language  has 
been  developed,  and  the  design,  coding  and  testing  of  the  required  software 
modules  are  in  progress.  Implementation  will  be  accomplished  during  the 
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third  quarter  of  1977.  The  major  features  added  for  the  purpose  of  de- 
scribing program  input  requirements  are  given  below.  A complete  descrip- 
tion of  the  language  constructs  for  the  ID  language  is  contained  in 
Appendix  B. 


3.3.1 


Parameter  Description 


A capability  has  been  included  to  allow  a description  to  be 
associated  with  each  input  parameter.  This  is  accomplished  with  a DEFINE 
statement.  When  a variable  is  so  defined,  its  description  is  available  to 
users  on  request  during  input  preparation  by  typing  a "?"  and  the  name  of 
the  parameter  or  parameters  desired. 


Format  Description 


A statement  is  included  for  describing  input  formats.  It  can 
be  used  to  specify  a list  of  parameters  and  the  format  in  which  they  must 
be  supplied  to  the  program.  It  is  an  extension  to  the  PUT  statement  and 
is  identical  in  form  to  the  PUT  EDIT  capability  in  PL/ I.  However,  instead 
of  taking  elements  in  the  list,  converting  them,  if  necessary,  and  out- 
putting  them  according  to  the  format  given,  the  PUT  statement  takes  the 
elements  and  checks  them  against  any  type  or  limit  specifications  given 
in  the  macro  (see  below)  and  then,  only  if  they  are  correct,  outputs  them 
as  specified  in  the  format.  Errors  in  input  values  will  be  displayed  to 
the  user  and  he  will  be  allowed  to  correct  them.  The  PUT  statement  will 
then  be  re-executed  automatically. 


3.3.3 


:>e  Specification 


A TYPE  statement  has  been  included  which  allows  specification 
of  the  type  requirements,  if  any,  which  a parameter  or  set  of  parameters 
must  satisfy.  For  example,  a set  of  parameters  can  be  required  to  be 
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integers  or  real  numbers  or  characters . The  PUT  statement  will  check  each 
parameter  in  the  list  to  see  if  a type  specification  has  been  given  for 
it.  If  so  the  value  supplied  will  be  checked  against  the  type  specified. 


In  a similar  manner  a range  or  set  of  acceptable  values  can  be 
specified  for  sets  of  parameters.  This  is  done  with  the  LIMIT  statement. 
For  example,  a parameter  can  be  required  to  be  between  the  values  0 and 
100  or  be  one  of  the  values  0,  1,  or  A.  Limit  specifications  are  handled 
in  exactly  the  same  manner  as  type  specifications. 
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SECTION  4.0 
PROGRAM  SELECTION 


4.1  OBJECTIVE 


The  purpose  of  this  component  of  ASSIST  is  to  provide  information 
to  the  user  regarding  available  applications  software.  The  nature  of  this 
information  will  be  such  that  he  may  determine  which,  if  any,  available 
programs  might  be  applicable  to  a given  problem.  Program  titles,  abstracts, 
development  and  revision  dates,  names  of  responsible  programmers,  and  pro- 
gram identification  (Reference  File)  numbers  are  examples  of  the  information 
to  be  provided.  Additionally,  this  information  will  be  made  conveniently 
accessible  from  a terminal.  Specifically,  a user  will  be  able  to  give  a 
keyword  or  list  of  keywords  and  a list  of  program  titles  will  be  searched 
for  the  occurrence  of  the  word  or  words  given.  The  program  titles  corre- 
sponding to  matched  keywords  are  returned  to  the  user.  He  may  then  list 
the  abstract  and  other  information  desired  for  selected  programs.  One  of 
the  primary  advantages  of  such  a capability  is  that  it  provides  an  effec- 
tive means  for  disseminating  information  regarding  available  software 
throughout  a large  community  of  users. 

4.2  APPROACH 

The  approach  taken  in  the  development  of  this  component  has  been  to 
create  an  on-line  data  set  containing  an  entry  for  each  PSI  macro  accessible 
through  the  program  submittal  component.  In  some  cases  there  may  be  more 
than  one  macro  for  a given  available  program,  but  there  is  always  at  least 
one.  The  entry  for  a given  macro  contains  its  name  (a  one  to  eight  char- 
acter identification),  a title,  the  name  of  the  responsible  programmer,  and 
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the  program  reference  file  (RF)  number  of  the  program  accessed  by  the  macro. 
This  RF  number  is  a key  into  an  existing  data  base  of  program  description 
information,  the  Program  Reference  File.  This  data  base  is  maintained  by 
the  Scientific  Computing  Division  and  contains  the  remainder  of  pertinent 
information  for  applications  programs.  This  data  base  will  be  placed  on- 
line and  the  capability  to  access  it  from  terminals  will  be  provided. 

4.3  PROGRESS 

An  on-line  data  base  containing  entries  for  all  PSI  macros  was 
created,  and  software  was  developed  to  permit  accessing  this  information 
from  terminals.  In  addition,  facilities  were  developed  for  adding, 
deleting,  and  modifying  the  data  base  information.  In  fact,  the  software 
which  allows  programmers  to  add  PSI  macros  was  designed  to  require  that  a 
descriptive  title  be  given  before  the  macro  is  added  to  the  macro  library. 
When  a macro  is  modified  the  descriptive  title  can  be  changed  and  when  a 
> macro  is  deleted  so  is  its  title  entry.  Thus,  the  data  base  of  descriptive 

titles  always  reflects  the  current  status  of  available  programs.  Two 
commands  have  been  provided  for  accessing  information  in  this  data  base. 

The  first  command,  called  DESCI-LAC,  can  be  used  to  obtain  the  descriptive 
title  for  a PSI  macro  by  giving  its  name.  The  second,  SCANMA CS,  scans 
the  entire  data  base  for  a keyword  supplied  and  returns  all  entries  con- 
taining that  word. 

Although  the  Program  Reference  File  data  base  has  been  placed 
on-line,  the  link  between  it  and  the  PSI  macro  data  base  has  not  been 
completely  established,  and  the  capability  to  access  it  from  a terminal 
has  not  been  developed.  These  items  are  scheduled  for  completion  during 
the  third  quarter  of  1977.  Also  the  feasibility  of  extending  the  search- 
ing capability  to  include  Boolean  combinations  of  keywords  will  be  studied. 
This  capability  would,  for  example,  allow  a user  to  ask  for  all  macro 
titles  containing  both  the  words  "structural"  and  "analysis"  or  just  the 
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single  word  "structures"  or  to  ask  for  all  titles  containing  the  word 
"loads"  but  not  the  word  "dynamic".  A second  extension  will  also  be 
studied  which  would  allow  direct  searching  of  the  Program  Reference  File 
data  base,  including  abstracts,  in  a similar  manner.  These  extensions 
will  be  evaluated  during  the  fourth  quarter  of  1977. 


) 
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SECTION  5.0 

USAGE  MONITORING  AND  CONTROL 

5.1  OBJECTIVE 

The  purpose  of  thisl  component  of  ASSIST  is  to  ensure  the 
efficient  usage  of  available  computer  resources  by  developing  adequate 
system  controls  and  through  the  monitoring  of  user  activity.  Since  ex- 
tensive computer  software  and  hardware  resources  have  been  made  available 
to  non  programming  users,  there  is  a need  to  prevent  inadvertent  misuse 
due  to  lack  of  computer  experience.  As  a minimum,  sufficient  information 
must  be  collected  in  order  to  determine  whether  the  resources  are  being 
efficiently  utilized.  The  information  so  collected,  since  it  will  reflect 
user  activity,  will  also  be  valuable  for  guiding  efforts  to  improve  the 
efficiency  of  ASSIST  itself. 

) 

5.2  APPROACH 

In  an  environment  where  virtually  all  computing  capabilities 
have  been  given  to  non  programming  users,  it  is  a practical  impossibility 
to  protect  the  hardware  and  software  from  deliberate  misuse.  The  approach 
in  this  research  is  twofold.  Firstly,  wherever  possible,  the  accidental 
misuse  of  resources  will  be  prevented.  All  components  of  ASSIST  have  been 
designed  so  that  the  checking  of  user  supplied  values  and  requests  is 
possible,  and  in  many  cases  the  required  parameters  which  effect  the  usage 
of  resources  are  automatically  determined.  Secondly,  statistics  regarding 
the  usage  of  resources  will  be  collected.  While  misuse,  either  accidental 
or  deliberate,  can  not  be  prevented  this  way,  it  can  at  least  be  discovered 
after  the  fact.  This  can,  of  course,  be  a great  deterrent  to  potential 
misusers  as  well  as  a means  to  correct  practices  which  result  in  ineffi- 
ciencies . 

) 
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5.3  PROGRESS 

The  accomplishments  toward  prevention  of  accidental  misuse  of 
resources  were  designed  and  implemented  within  the  Program  Submittal  and 
Input  Preparation  components  of  ASSIST.  By  their  very  nature  these  com- 
ponents eliminate  many  sources  of  user  errors.  The  Program  Submittal 
component  automatically  determines  many  required  parameters,  and  both 
components  have  capabilities  for  checking  the  correctness  of  user  supplied 
values.  In  the  case  of  program  submittal,  the  computer  resources  requested 
(e.g.  core,  time,  lines  of  output,  etc.)  can  be  controlled,  and,  in  the 
case  of  input  preparation,  the  execution  of  runs  with  erroneous  data  can 
be  prevented. 

Beyond  these  capabilities,  the  primary  method  for  ensuring  the 
efficient  use  of  resources  has  been  through  the  collection  and  analysis 
^ of  data  relating  to  user  activity.  Much  of  the  relevant  data  is  available 

for  terminal  sessions  just  as  it  is  for  normal  batch  work  through  the 
standard  accounting  procedures.  In  addition  to  this  data,  a module  has 
been  designed  and  implemented  experimentally  which  collects  information 
regarding  batch  submittals  made  by  terminal  users.  The  standard  account- 
ing procedures,  of  course,  collect  the  same  information  about  these  re- 
motely submitted  runs  as  they  do  for  normal  batch  jobs.  This  new  module, 
however,  additionally  collects  the  following  information  for  each  run. 

o Userid  of  submitter 
o PSI  macro  used 
o Time,  line,  and  card  estimates 
o Priority  requested 
o Date  and  time  of  submittal 

This  data  can  be  used  not  only  to  ensure  the  proper  use  of 
resources  by  terminal  users,  but  to  determine  the  level  of  use  and  actual 
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users  of  each  PSI  macro.  Although  this  module  has  been  coded  and  tested, 
it  has  not  been  implemented  in  a production  mode  because  the  current  re- 
sponse problems  during  submittal  will  not  permit  the  monitoring  of  activity. 
Once  response  improves  to  a satisfactory  level,  this  module  can  be  added. 

During  1977  the  feasibility  of  monitoring  other  activities  of 
users  will  be  considered  and  software  will  be  developed  to  produce  mean- 
ingful reports  from  all  available  information  on  user  activity. 


) 
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SECTION  6.0 
CONCLUSIONS 

The  success  experienced  with  early  versions  of  ASSIST  has  con- 
tinued with  improved  implementations.  The  present  version  clearly  de- 
monstrates the  practicality  of  augmenting  existing  application  software 
with  a communications  interface  system.  Some  of  the  specific  benefits 
of  this  system  are  as  follows : 

(1)  By  eliminating  the  need  for  communication  with  professional  programmers, 
errors  due  to  misunderstandings  disappear  and  elapsed  processing  time 

is  reduced. 

(2)  By  providing  simple  and  direct  communication  with  the  computer,  the 
productivity  of  the  user  is  increased. 

(3)  By  checking  user  input  data  and  automatically  generating  job  control 
information,  execution  errors  are  greatly  reduced. 

(4)  Making  information  about  software  centrally  and  easily  available  and 
providing  a convenient  means  for  using  it  results  in  a greater 
utilization  of  available  software  and  less  duplication  of  program 
development  of  effort. 

By  the  end  of  1976,  180  programs,  or  versions  of  programs,  were 
directly  available  to  users  through  ASSIST.  Included  in  this  number  are 
several  major  computing  systems,  such  as  FAMAS  (Flutter  And  "atrix  Igebra 
Systan)  and  the  'IASTRAN  (NAsa  STRuctural  Analysis)  system.  In  addition, 
ASSIST  includes  utility  functions  to  allow  users  to  print  and  punch  data 
sets  and  to  compile  small  FORTRAN  and  PL/l  programs.  The  number  of  users 
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at  the  end  of  1976  was  172,  and  more  than  100  runs  were  being  made  daily 
through  ASSIST.  ASSIST  has  been  used  to  great  advantage  in  almost  every 
area  of  engineering  analysis,  as  well  as  some  areas  of  financial  analysis, 
and  recently  in  manufacturing.  Significant  cost  savings  have  resulted, 
primarily  due  to  reductions  in  elapsed  time  to  complete  analyses  and 
through  the  elimination  of  many  sources  of  error.  For  example,  the 
structural  engineering  organization  has  reported  that  ASSIST  was,  in  part, 
responsible  for  obtaining  a dramatic  improvement  in  both  cost  and  schedule 
in  determining  external  strength  level  loads  for  the  L-1011-500. 

Future  developments  in  the  area  of  user  oriented  remote  com- 
puting will  be  at  two  levels.  For  the  short  term,  efforts  will  be 
directed  at  improving  the  performance  characteristics  and  basic  capabil- 
ities of  the  present  version  of  ASSIST.  The  major  effort,  however,  will 
be  directed  toward  determining  the  proper  hardware  and  software  con- 
figuration for  providing  users  with  remote  computing  capabilities.  Both 
the  short  term  and  long  term  efforts  have  been  strongly  influenced  by  the 
results  of  a questionnaire  which  was  distributed  to  DCAS  users  on  ’lay  20, 
1976.  The  complete  results  and  analysis  of  this  questionnaire  are  given 
in  Appendix  C. 

Although  the  responses  to  the  questionnaire  indicated  a highly 
favorable  attitude  toward  ASSIST,  there  were  many  constructive  suggestions 
for  improvement.  The  main  criticism  of  the  system  was  its  poor  responsive- 
ness, a problem  not  with  the  ASSIST  software  but  with  the  overall  hardware 
and  system  software  environment  in  which  ASSIST  is  imbedded.  Neither  the 
IB,'-'  360/91  hardware  nor  the  0S/MVT  software  (the  current  operating  system) 
were  designed  to  support  time  sharing  applications.  Consequently,  TS0, 

IBV's  time  sharing  system  which  hosts  ASSIST,  has  severe  performance  pro- 
blems. Furthermore,  due  to  the  wide  acceptance  and  overall  success  of 
DCAS,  the  number  of  users  is  expected  to  grow  steadily  over  the  next  several 
years,  adding  to  the  difficulty  of  providing  adequate  performance. 
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Several  approachs  toward  improving  system  responsiveness  and 
capacity  are  possible.  The  first  is  simply  to  dedicate  sufficient  com- 
puting resources  to  achieve  the  desired  level  of  response  for  the  current 
number  of  users,  an  expensive  but  simple  solution.  The  second  approach  is  to 
replace  TSO  with  a time  sharing  system  designed  to  compensate  for  some  of 
the  inadequacies  of  the  existing  hardware  and  operating  system  software. 
Although  such  systems  exist,  none  offers  the  range  of  capabilities  avail- 
able under  TSO,  and  extensive  retraining  of  users  would  be  required  if 
such  a change  were  made.  Because  systems  still  must  contend  with  hardware 
and  operating  system  software  which  are  inherently  inefficient  for  the 
purposes  of  time  sharing,  a truly  efficient  replacement  system  is  im- 
possible. A third  approach  is  to  move  the  interactive  functions  from  the 
IBM  360/91  onto  a machine  or  machines  better  designed  to  support  such 
activity.  In  this  environment,  a user  would  be  connected  to  a satellite 
computer  capable  of  handling  interactive  functions  directly  and  be  con- 
nected to  the  IBM  host  machine  to  provide  remote  batch  capabilities.  Such 
a distributed  system,  while  possibly  solving  the  major  performance  pro- 
blems, introduces  many  other  potential  difficulties.  Not  the  least  of 
which  are  those  related  to  the  communication  between  the  satellite  com- 
puter^) and  the  host.  The  major  effort  on  this  research  task  during 
1977  will  be  to  determine  the  potential  value  and  practicality  of  such  a 
distributed  system  for  providing  user-oriented  remote  computing  capabilities. 
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APPENDIX  A 

GUIDE  TO  WRITING  A PS  I MACRO 


A.l  INTRODUCTION 

A PS  I (Program  Setup  Instructions)  macro  is  just  a generalized 
set  of  JCL  (where  JCL  is  taken  to  mean  all  actual  JCL,  LASP  control  state- 
ments, linkage  editor  input,  etc.).  This  generalized  JCL  is  analyzed  by 
a preprocessor  (RUNPROG),  and  from  it  a complete  job  for  batch  execution 
is  built.  In  writing  a PSI  macro  it  is  usually  best  to  start  with  a set 
of  JCL  as  would  be  required  for  a batch  submittal  and  make  modifications 
to  it  as  indicated  in  the  following  sections. 

A. 2 STRUCTURE  OF  A PSI  MACRO 

A PSI  Macro  can  contain  three  types  of  statements: 

(1)  System  Control  Statements 

These  are  the  IBM  System/360  JCL  statements,  LASP  statements, 
linkage  editor  input,  and  other  data.  These  obey  the  normal  rules 
for  syntax  except  they  may  optionally  contain  PSI  variables  (see 
section  A.4). 

(2)  Comment  Statements 

Comments  may  be  written  in  columns  2-80  of  a card  if  a 'C'  is  placed 
in  column  1.  Comment  cards  are  ignored  by  the  preprocessor. 

(3)  Preprocessor  Statements 

These  are  special  statements  which  control  the  creation  of  the  job 
to  be  submitted.  These  statements  are  coded  in  columns  2-72  and 
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mast  be  prefixed  with  a ' $ ' symbol  in  column  1.  These  statements 
are  stream  rather  than  card  oriented  and  hence  each  must  be  ter- 
minated with  a semicolon.  The  preprocessor  statements  currently 
available  are: 

(a)  The  Macro  Definition  Statement  (See  Section  A. 6) 

(b)  The  Macro  End  Statement  (See  Section  A. 6) 

(c)  The  Input  Statement  (GET  - see  Section  A. 9) 

(d)  The  Output  Statement  (PUT  - see  Section  A. 9) 

(e)  The  Conditional  Statement  (IF  - see  Section  A. 10) 

(f)  The  Group  Delimiting  Statements  (DO  & END  - see  Section  A. 10) 

(g)  The  Assignment  Statement  (See  Section  A. 11) 

(h)  The  Iteration  Statement  (DO  WHILE  - see  Section  A. 12) 


A PS I macro  should  begin  with  a macro  definition  statement  and 
end  with  a macro  end  statement  (although  neither  is  presently 
required).  The  other  preprocessor,  comment,  and  system  control 
statements  can  occur  anywhere  within  a PS I macro. 

A. 3 N0TATI0KAL  CONVENTIONS 

'When  describing  the  syntax  of  preprocessor  statements,  the  follow- 
ing notational  conventions  will  be  used. 


(1)  The  brackets,  ' f 1 and  ' ] ' wil 


1 surround  items  which  may  optionally 


be  present. 


(2)  The  braces 


’ and  ’ t ' will  mean  that  one  of  the  enclosed  items 


must  be  chosen. 


(3)  Strings  of  lower  case  letters  are  used  to  indicate  variables  which 
must  be  replaced  with  some  value. 
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(4)  Strings  of  upper  case  letters  indicate  information  which  must  be 
present  exactly  as  written. 

(5)  The  ellipsis,  indicates  that  the  previous  item  may  be  re- 

peated an  arbitrary  number  of  times. 


For  example,  in  the  specification 


ASSIGN  identifier 


[{:} 


1 


constant J ...  TO  subscript 

'ASSIGN'  and  'TO'  must  appear  literally,  'identifier',  'constant', 
and  'subscript'  are  variables  which  must  be  replaced  with  values 


whenever  they  occur,  ' W constant'  is  optional  and  it  may  occur 
sequentially  any  number  of  times,  but  each  time  a choice  must  be 
made  between  '+'  and 


A.  4 PS  I VARIABLES 

Any  item  (or  portion  of  a statement)  within  a JCL  set  which 
may  assume  different  values  with  different  submittals  may  be  given  a 
symbolic  name  so  a value  can  be  assigned  when  the  actual  submittal  is 
made.  This  name  can  consist  of  up  to  eight  (8)  characters.  It  must 
begin  with  a letter  and  can  contain  only  letters,  digits,  break  characters 
(_),  and  national  characters  ($,#,<§).  This  symbolic  name  can  be  used  for 
any  item  in  a JCL  statement  by  enclosing  it  between  the  symbols  ' < ' and 
' >'  and  writing  this  string  in  place  of  the  given  item.  For  example, 
suppose  the  running  time  for  some  program  varies  with  the  input  data. 

One  could  then  write  the  following  statement : 


/ *MAIN  LINES=20,CARDS=50,TIME=< RUNTIME > 

This  would  allow  specification  of  value  for  the  variable  RUNTIME  when 
the  program  is  submitted  for  execution. 


) 
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’When  the  substitution  of  a value  occurs,  that  value  normally 
replaces  exactly  the  string  ' < ' followed  by  the  variable  name  followed 
by  * >'  (for  exceptions  to  this  see  Section  A. 5).  If  the  length  of  the 
value  is  less  than  that  of  the  string  it  replaces  then  the  remainder  of 
the  statement  will  be  moved  left  so  as  to  immediately  follow  the  value 
inserted.  Correspondingly  if  the  value  is  greater  in  length  than  the 
string  it  replaces,  the  remainder  of  the  statement  will  be  shifted  right 
an  appropriate  number  of  spaces.  If  more  than  one  variable  is  to  be 
replaced  in  a statement,  replacement  proceeds  fran  left  to  right. 

This  substitution  of  values  can  cause  a statement  to  exceed 
the  maximum  allowable  length  for  that  type  of  statement.  For  actual  JCL 
and  LASF  statements,  RUNFROG  automatically  produces  continuation  cards 
when  this  condition  occurs.  All  other  statements  are  truncated  after  72 
columns. 

FSI  variables  may  also  be  used  in  preprocessor  statements  as  in 
any  programming  language.  In  this  case  they  are  not  surrounded  by  the 
delimiters  ' < ' and  ' > ' . The  same  variable  name  may  appear  in  both  a 
system  control  statement  (surrounded  by  ' < ' and  ' >' ) and  in  a pre- 
processor statement  and  will  have  the  same  value  in  both  contexts. 

A. 5 SPECIFYING  COLUMNS  FOR  STRING  REPLACEMENTS 

Sometimes  it  is  necessary  to  insure  that  the  value  replacing 
some  variable  name  begins  in  a particular  column.  This  can  be  accomplish- 
ed by  prefixing  the  variable  name  with  the  symbol  ' ' and  the  desired 
column  number.  For  example,  an  accounting  card  could  be  written  as 
follows : 

/*AC<  USERNAME  '><@19$CSR#X@33CODE  ><§34 FROG#  > <@M+$DP#  > . . . 
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In  this  case  the  value  of  $CSR//  would  begin  in  column  19,  the  value  of 
CODE  in  column  33,  and  so  on.  Replacement  proceeds  from  left  to  right  so 
if  the  same  columns  are  affected  by  two  replacements  the  latter  one  over- 
rides the  former.  For  example,  if  the  value  of  CODE  had  length  2 it  would 
occupy  columns  33  and  34  after  the  replacement.  However,  the  replacement 
of  PROGy  by  its  value  would  modify  col’.nnn  34  again  and  the  second  character 
of  CODE  in  this  statement  would  be  destroyed. 

A literal  string  can  also  be  placed  in  a specified  column  by 
enclosing  it  within  quotes.  For  example,  the  accounting  card  could  be 
rewritten  as  follows : 

/*AC<  USERNAME  >^19$CSRO'C333’l,>  < @34 '1234 ' > < ®44-$dp#  > . . . 

This  would  place  a '1'  in  column  33  and  the  string  '1234'  in  columns  34 
through  37. 

) 

A. 6 NAMING  A PS  I MACRO 

The  name  of  a PSI  macro  should  begin  with  the  letter  'P',  which 
should  be  followed  by  the  reference  file  number  for  the  program  being 
executed,  and  this  can  optionally  be  followed  by  any  string  of  alphameric 
characters.  The  total  length  of  the  name,  however,  may  not  exceed  8 
characters.  Other  names  may  be  used  if  there  is  sufficient  reason  and 
if  prior  approval  is  obtained. 

This  macro  name  should  appear  on  a macro  definition  statement 
which  should  be  the  first  statement  of  the  macro.  The  form  of  this  state- 
ment is  as  follows : 

°!o  name:  MACRO  identifier=constant  [", ident if ier=constant"l  ...; 


) 

-5 
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where  'name'  is  the  PS I macro  name 

'identifier'  is  any  variable  name 

'constant'  is  an  integer  or  character  string  default  value  for 
the  variable  (see  Section  A. 7) 

The  macro  name  may  also  appear  on  the  macro  end  statement  which 
should  be  the  last  statement  of  the  macro..  The  form  of  this  statement 
is  as  follows: 

% MEND  name  ; 

where  'name'  is  the  PSI  macro  name. 

As  an  example  suppose  a PSI  macro  were  being  developed  to 
execute  a program  whose  reference  file  number  was  '1234'.  The  macro 
would  probably  be  named  P1234  and  would  begin  with  the  statement 
% P1234 : MACRO; 

and  end  with 

) % MEND  P1234; 

This  macro  name  will  also  be  used  in  storing  the  macro  into  the  PSI  macro 
library  (see  Section  A.l4). 

A. 7 ESTABLISHING  DEFAULT  VALUES  FOR  VARIABLES 

Default  values  may  be  given  to  PSI  variables  by  listing  them 
on  a macro  definition  statement  (see  Section  A. 6 for  a complete  descrip- 
tion of  this  statement).  For  example,  suppose  one  wanted  to  have  a 
default  running  time  of  2 minutes  for  some  program  but  still  allow  the 
user  to  override  the  time  if  necessary.  This  could  be  accomplished  by 
using  the  following  macro  definition  statement. 

% P1234 : MACRO  RUNTIMES; 

Default  values  can  be  established  only  for  those  variables  which  .ave  ■ t 
been  assigned  values  prior  to  invocation  of  the  macro.  hat  is,  some 
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variable  names  have  built-in  default  values,  and  the  macro  definition 
statement  cannot  be  used  to  specify  different  default  values.  A complete 
list  of  these  system  variables  and  their  defaults  is  given  in  the  Table  on 
the  following  page. 

The  system  variables  fall  into  2 classes. 

(1)  User  Information  Variables 

These  contain  information  relating  to  the  user  and  their  values  are 
automatically  determined  based  upon  the  "userid"  and  "account" 
specified  by  the  user  at  logon. 

Specifically  they  are : 


(a) 

$USERID 

userid 

(b) 

$CSR# 

dcas  account  number 

(c) 

^CHARGE# 

- class -work  order,  ewa,  and  serial  number  associa- 
with  dcas  account  number 

(d) 

$DI# 

department  number  associated  with  account  number 

(e) 

$GF# 

- group  number  associated  with  account  number 

(f) 

JOBNAME 

- name  to  be  given  the  submitted  job 

(s) 

USERNAME 

- user  name  associated  with  userid 

00 

USERDEPT 

department  number  associated  with  userid 

(i) 

BIN# 

address  (i.e.  building  number  or  bin  number) 
where  output  is  to  be  sent 

(2 ) Convenience  Variabi.es 


The  remainder  of  the  variables  listed  in  the  Table  were  provided  merely 
as  a convenience  in  using  the  early  versions  of  RUNFROG  which  did  not 
allow  the  setting  of  default  values.  At  some  time  in  the  future  the 
default  values  for  all  of  these  variables  will  be  eliminated.  There- 
fore, new  macros  should  explicitly  specify  the  defaults  for  any  of 
these  variables  used,  and  existing  macros  should  be  so  modified. 
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Variable  Name 

$CARDS 
$ CLASS 
$ CHARGE# 
$CSR# 

$DP# 

$GP# 

$ LINES 

$FRTY 

$REGION 

$TIME 

$USERID 

BIN# 

CODE 

DATA 

JOBNAME 

OBJECT 

PROG# 

PRTY 

SOURCE 

USERDEPT 

USERNAME 

XCHAR 


Default  Value 

'O' 

'B' 

automatically  determined 
automatically  determined 
automatically  determined 
automatically  determined 

'5 ' 

'O' 

’200K’ 

'1' 

automatically  determined 
automatically  determined 

'2' 

a null  data-set 
automatically  determined 
a null  data-set 
'469000' 

'O' 

a null  data-set 
automatically  determined 
automatically  determined 
'A' 


Table . 


RUNEROG  System 


Variables  and  Defaults 
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A default  value  may  be  any  preprocessor  constant.  Preprocessor 
constants  may  be  numbers  or  character  strings.  A number  may  be  written 
as  a fixed  point  or  floating  point  decimal  number.  A fixed  point  decimal 
number  consists  of  1 to  15  decimal  digits  with  an  optional  decimal  point. 

If  no  decimal  point  appears,  the  point  is  assumed  to  be  immediately  to 
the  right  of  the  rightmost  digit.  A floating  point  decimal  number  is 
written  as  a fixed  point  decimal  number  followed  by  the  letter  E,  followed 
by  an  optionally  signed  decimal  integer  exponent  (of  no  more  than  2 digits'. 
Any  numeric  constant  may  optionally  be  preceded  by  a plus  or  minus  sign. 
Blanks  may  not  appear  within  a numeric  constant.  The  following  are  ex- 
amples of  valid  numeric  constants . 

3.141593 

732 

003 

.0012 

x 3141593E-6 

7.32E+2 
.003E3 

A character  string  constant  is  any  string  of  up  to  80  valid 
characters  enclosed  withi.  single  quotation  marks.  If  a single  quotation 
mark  is  a character  in  the  string,  it  must  be  written  as  two  single 
quotation  marks  with  no  intervening  blanks.  If  two  single  quotation  marks 
are  used  within  the  string  to  represent  a single  quotation  mark  they  are 
counted  as  a single  character.  A null  character  string  constant  is 
written  as  two  quotation  marks  with  no  interleaving  blank.  Examples  of 
character  string  constants  are: 

•TITLE' 

’SHAKESPEARE' 'S'  " ' HAMLET ’ " ” 

•3.141593' 

' ' (null  character  string  constant) 


mm 
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A. 8 OVERRIDING  DEFAULT  VALUES 


If  a default  value  has  been  provided  for  a variable,  it  may  be 
overriden  by  the  user  as  follows: 

(1)  He  must  include  the  specification  "M0REPARK(YES )"  when  using  the 
RUNPROG  command  (See  Section  A.l6).  For  example: 

RUNFROG  P123U  DATA (X. DATA)  MORE PARK (YES ) 

(2)  RUNFROG  will  then  give  him  the  opportunity  to  override  default  values. 
For  each  variable  he  wishes  to  change  he  must  type  the  variable  name 
followed  by  an  equal  sign  followed  by  the  value  he  wishes  that  var- 
iable to  have  (character  string  values  must  be  enclosed  in  quotes  but 
numeric  values  need  not  be).  Multiple  specifications  can  be  given 

by  separating  them  by  blanks  or  commas.  Entering  a null  line  termi- 
nates this  mode  and  RUNPROG  resumes  processing  of  the  macro. 

A. 9 COMMUNICATING  WITH  THE  USER 

Input  (GET)  and  output  (PUT)  statements  are  available  for 
obtaining  and  providing  user  information.  The  GET  statement  has  the 
form, 

% GET  identifier; 

where  ’identifier’  is  any  variable  name 
The  execution  of  such  a statement  will  cause  one  line  (80  characters)  of 
information  to  be  read  from  the  user's  terminal.  Trailing  blanks  are 
eliminated  and  the  resulting  string  is  stored  as  a value  for  the  variable 
specified  by  ’identifier’.  A null  line  or  a line  of  blanks  are  interpreted 
as  a single  blank  character.  A separate  GET  statement  is  (presently)  re- 
quired for  each  value  to  be  obtained. 
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Since  execution  of  the  GET  statement  will  cause  the  program  to 
pause  and  wait  for  the  user  to  respond,  it  is  usually  necessary  to  give 
him  some  prior  indication  as  to  what  information  will  he  required  of  him. 
This  can  be  done  with  the  PUT  statement.  In  fact  the  PUT  statement  can 
be  used  anytime  it  is  desired  to  issue  a message  to  the  user.  It's  form 
is  as  follows : 

identifier 
constant  ’ 

where  'identifier'  is  any  variable  name 

and  'constant'  is  any  preprocessor  constant  (See  Section  A. 7) 

The  execution  of  a PUT  statement  will  cause  the  value  of  the  identifier 
or  constant  specified  to  be  displayed  at  the  terminal.  A separate  PUT 
statement  is  (presently)  required  for  each  value  to  be  output.  An  example 
of  the  use  of  the  GET  and  FJT  statements  is  as  follows: 

% PUT  'PLEASE  SUPPLY  A VALUE  FOR  X'; 

% GET  X; 

Communication  with  the  user  can  also  occur  without  the  explicit 
use  of  the  GET  and  PUT  statements.  Whenever  a variable  is  encountered 
for  which  no  value  has  been  assigned  (either  by  the  system  or  from  some 
prior  statement  within  the  macro),  RUNPROG  will  prompt  the  user  for  a 
value.  For  example,  if  no  value  had  been  given  for  the  variable  RUNTIME, 
the  processing  of  the  statement. 

/*MA IN  LINES =20 , CARDS  =5 , TIME* < RUNTIMES 

would  result  in  the  following  message  being  displayed  at  the  user's 
terminal. 

RUNTIME  = ? 

RUNPROG  would  then  accept  a value  from  the  user  for  this  variable,  just 
as  if  a GET  statement  had  been  executed,  and  process  the  statement  using 
the  supplied  value.  This  variable  will  now  have  the  value  specified  by 
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the  user,  unless  altered  by  an  assignment  statement  (see  Section  A. 11)  or 
an  explicit  input  statement,  for  the  remainder  of  the  processing  of  the 
macro.  Hence,  if  another  statement  containing  the  same  variable  name  is 
encountered, 

//  EXEC  i'ORTLG , FARM.  G=  < RUNT  IME  > 

the  same  value  will  be  used  and  the  user  will  not  be  prompted  again. 

The  user  may  also  specify  values  for  variables  using  the  same 
technique  as  was  required  for  overriding  default  values  (see  Section  A. 8) 
even  for  variables  with  no  established  defaults.  The  user  could  thus 
supply  all  required  inputs  at  once  and  avoid  being  prompted  for  each  item 
individually  except  1.  cases  where  the  explicit  input  (GET)  and  output 
(JUT)  statements  are  used.  (The  GET  statement  will  always  require  the 
user  to  supply  a new  value  for  a variable  even  if  the  variable  already 
has  a value). 

A. 10  SPECIFYING  ALTERNATIVES 

PS  I macros  may  be  written  in  such  a way  as  to  cause  some  JCL 
statements  to  be  included  in  the  job  being  built  only  under  certain 
conditions.  This  may  be  accomplished  by  use  of  the  preprocessor  con- 
ditional statement.  For  example,  suppose  a given  program  could  optionally 
produce  plot  output.  The  macro  could  be  written  in  such  a way  as  to  in- 
clude the  setup  and  DD  cards  for  the  plot  tape  and  the  necessary  instruc- 
tions to  the  operator  (via  operator  cards)  only  for  the  runs  which  actually 
generate  plots.  A variable,  say  PLOTS,  could  be  selected  as  the  test  var- 
iable and  one  could  write 

io  IF  PLOTS  =' YES'  THEN 

/ *SETUP  D DNA' ' E=  PLOTT A PE , . . . 

This  would  cause  the  setup  card  to  be  included  only  if  the  value  of  PLOTS 
was  'YES'.  If  PLOTS  had  not  been  assigned  a value  prior  to  execution  of 
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the  IF  statement  then  the  user  would  be  prompted  for  a value.  If  more 
than  one  statement  is  to  be  optionally  included  based  upon  some  test  then 
that  group  of  statements  must  be  preceded  by  the  preprocessor  statement, 

% DO; 

and  followed  by  the  preprocessor  statement 

°!o  END; 

For  example,  one  might  write  the  following: 

1o  IF  PLOTS=' YES  ' THEN 
$ DO; 

/ *SETUP  DDNA:.£=PLOTTAPE,  . . . 

/♦OPERATOR. . . 

/♦OPERATOR. . . 
io  END; 

In  this  case  the  setup  and  operator  cards  will  all  be  included  or  all 
omitted  depending  upon  the  value  of  PLOTS. 


The  conditional  statement  must  have  the  following  form. 


IF 


identifier 


constan 


re  lop 


THEN  statement-block 


identifier 
constant 

where  ’identifier’  can  be  any  variable  name 

’constant’  can  be  any  preprocessor  constant  (see  Section  A. 7) 
1 relop ’ must  be  either  the  relational  operator  ’ =’  (equal)  or 
= ' (not  equal) 

'statement-block'  can  be  either  a single  statement  or  a group 
of  statements  preceded  by  a DO  statement 
and  followed  by  an  END  statement. 


Conditional  statements  may  be  nested  to  any  depth.  The  follow- 
ing are  valid  examples  of  the  use  of  IF  statements. 

% IF  A=1  THEN 
°!o  DO; 

(group  of  statements) 
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> 

IF  B=2  THEN 
DO; 

(group  of  statements) 

IF  C=3  THEN 

(statement ) 

END; 

END; 

</>  IF  A *1  THEN 
% DO; 

(group  of  statements) 

i IF  B=2  THEN 
t DO; 

(group  of  statements) 

END; 

(group  of  statements) 

% end; 

A. 11  ASSIGNING  VALUES  TO  VARIABLES 

A limited  form  of  an  assignment  statement  is  available  in  the 
present  version  of  RUNPROG.  This  statement  is  written  as  follows. 

'%  identifier  = constant; 
where  'identifier'  is  any  variable  name 

'constant'  is  any  preprocessor  constant 
One  example  of  the  use  of  this  statement  is  the  following: 

% FRTY=3; 

c,o  IF  TIME  7=2  THEN 
1o  FRTY=1; 

Here  FRTY  is  given  the  value  3 as  long  as  TIME  is  2 (presumably  the 
default  value),  otherwise  FRTY  is  changed  to  1. 


1o 

1o 

n/ 

to 

i 

1° 
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A. 12  PERFORMING  ITERATION 


1 


) 


Sometimes  it  is  necessary  to  repeat  a statement  or 
statements  within  a job  being  built.  .his  repetition  can  be 
with  the  preprocessor  DO  WHILE  statement.  It's  syntax  is  as 


group  of 
accomplished 
follows : 


DO  'WHILE  ( 


identifier 

constant 


relop 


identifier 

constant 


); 


where  'identifier1  is  any  variable  name. 

'constant'  is  any  valid  preprocessor  constant, 
'relop'  is  either  the  relational  operator 
' = ' (equal)  or  ' 7 ='  (not  equal) 


The  end  of  the  repetition  loop  is  indicated  by  the  preprocessor  END  state- 
ment.. The  loop  may  contain  statements  of  any  type  (preprocessor,  JCL, 
etc.),  and  the  group  will  be  repeated  as  long  as  the  condition  of  the 
DO  WHILE  remains  true.  For  example,  suppose  the  input  data  to  some  pro- 
gram could  exist  on  several  data-sets  which  would  have  to  be  concatenated 
together  in  order  to  make  a run.  Rather  than  requiring  the  user  to  do  the 
necessary  merging,  the  following  code  could  be  included  within  a PS I macro. 


//SYS IN  DD  DSN=< INPUT >,DISP=SHR 
% PUT  'SUPPLY  NEXT  INPUT  DATA-SET  NAME'; 
i TJT  'OR  HIT  CARRIER  RETURN  IF  NONE'; 

% GET  INPUT; 

i DO  WHILE  (INPUT  7=  ")} 

//  DD  DSN=  < INPUT  >,DISP=SHR 

°!o  FJT  'SUPPLY  NEXT  INPUT  DATA-SET  NAME' ; 

i PUT  'OR  HIT  CARRIER  RETURN  IF  NONE'; 

°!o  GET  INPUT} 
t END; 


) 
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After  the  initial  'DD'  card  is  written  into  the  job  stream  the 
user  is  prompted  for  another  data-set  name  by  use  of  the  PUT  and  GET 
statements  (see  Section  A. 9).  The  loop  is  then  entered  provided  the  value 
supplied  was  not  null.  A concatenation  'DD'  card  is  generated  and  the  user 
is  again  prompted  for  another  data-set  name.  Control  returns  to  the 
WHILE  statement  and  the  leop  is  exeeuted  again  as  long  as  the  last 
value  provided  was  not  null.  This  process  continues  until  a null  value 
is  given  for  a data-set  name.  Control  then  transfers  to  the  statement 
following  the  EOT)  statement. 

A. 13  BUILT-IN  FUNCTIONS 


The  built-in  functions  which  are  available  for  use  in  writing 
PSI  macros  are  described  below. 

A. 13.1  DSN  Built-in  Function 


Definition:  DSN  converts  a valid  TSO  specification  of  a data 

set  name  into  a form  acceptable  for  use  in  a Data  Definition  (DD)  state- 
ment, returning  the  converted  form  to  the  point  of  invocation,  (within 
TSO  a user  may  refer  to  one  of  his  data  sets  without  explicitly  including 
the  top  level  index,  namely  his  "userid".  He  may  also  refer  to  his  own 
or  any  other  catalogued  data  set  by  specifying  the  full  data  set  name  and 
enclosing  it  within  single  quote  marks  (').  In  a DD  statement,  however, 
the  full  data  set  name,  without  enclosing  quotes  must  be  given). 

Reference:  DSN  (string) 

Argument ; The  argument  "string"  represents  the  string  from 
which  a full  data  set  name  is  to  be  constructed. 
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Result : If  "string”  has  enclosing  quotes  the  value  returned  by 

this  function  is  the  "string"  with  the  enclosing  quotes  removed.  Other- 
wise, the  value  returned  is  a string  consisi ing  of  the  current  user's 
"userid"  followed  by  a point  (".")  followed  by  the  argument  "string". 

Examples : If  INPUT  had  the  value 

'E123456.XY7.DATA' 
the  statement 

% DATASET  = DSN( INPUT); 
would  assign  the  value 
E123456.XYZ.DATA 
to  the  variable  DATASET. 

If  INPUT  had  the  value 
XYZ.DATA 

and  the  current  user  was  E654321  then  the  statement  above  would 
«**asa  the  value 
E654321. XYZ.DATA 
to  be  assigned  to  DATASET. 

A. 13. 2 SUBSTR  Built-in  Function 


Definition:  SUBSTR  extracts  a substring  of  programmer  defined 

length  from  a given  string  and  returns  the  substring  to  the  point  of 
invocation. 


Reference : SUBSTR  (string, [i  ,j(]  ) 

Arguments : The  argument  "string"  represents  the  string  from 

which  a substring  will  be  extracted.  Argument  "i"  represents  the  starting 
point  of  the  substring  and  "J"  represents  the  length  of  the  substring. 
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Arguments  "i"  and  "j"  must  be  integers  or  variables  with  integer  values. 
Assuming  that  the  length  of  "string”  is  k,  arguments  "i"  and  "3"  must 
satisfy  the  following  conditions: 

(1)  j must  be  less  than  or  equal  to  k and  greater  than  or  equal  to  0. 

(2)  i must  be  less  than  or  equal  to  k and  greater  than  or  equal  to  1. 

(3)  The  value  of  i + j - 1 must  be  less  than  or  equal  to  k. 

Thus,  the  substring,  as  specified  by  "i"  and  "j"  must  lie  within 

"string".  If  "j"  is  not  specified,  it  is  assumed  to  be  equal  to  the  value 
of  k - 1 + 1.  In  other  words,  it  is  assumed  to  be  the  length  of  the  re- 
mainder of  "string",  beginning  at  the  ith  position  in  "string". 

Result : The  value  returned  by  this  function  is  a character 

\ string  determined  as  follows : 

(1)  If  j=0,  the  returned  value  is  the  null  string. 

(2)  If  j is  greater  than  0,  the  returned  value  is  that  substring  be- 
ginning at  the  ith  character  of  the  first  argument  and  extending  j 
characters . 

(3)  If  j is  not  specified,  the  returned  value  is  that  substring  be- 
ginning at  the  ith  character  and  extending  to  the  end  of  "string". 

Example : If  CHARGE  is  the  character  string 

21-3715  5407 
the  statement 

WO  = SUBS TR( CHARGE, 4,4); 

will  cause  a 4-character  substring  to  be  extracted  from  CHARGE, 
starting  at  the  4th  character.  This  substring, 

> 3715 

will  then  be  assigned  to  the  variable  WO. 
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A.lU  MAKING  A PSI  MACRO  AVAILABLE  FOR  USE 

Once  a PEI  macro  has  been  written  it  must  be  copied  into  the 
PSI  macro  library  before  it  can  be  used  with  RUNPROG.  This  library  is  a 
partitioned  data  set  where  each  member  is  a macro.  The  member  name  should 
be  exactly  the  same  as  the  name  given  the  macro. 

A special  DC  AS  command  is  available  for  putting  a new  member  in 
the  library  or  changing  an  existing  member.  This  command  is  named  ADDMAC 
and  has  two  positional  parameters.  The  first  is  the  name  of  a control 
(CNTL)  data  set  containing  the  macro  to  be  added  or  replaced  and  the  second 
is  the  name  of  the  macro.  For  example, 

ADDMAC  XYZ  F1234 

will  put  the  data  set  userid. XYZ. CNTL  into  the  macro  library  with  member 
name  P1234.  Notice  that  the  data  set  specified  must  be  of  type  CNTL  and 
exist  in  the  library  of  the  current  user  and  neither  the  userid  or  type 
are  specified  on  the  ADDMAC  command. 

An  existing  macro  can  be  changed  by  first  copying  the  appropriate 
member  of  the  macro  library  (which  is  named  TSOGURU.DCASJCL.CNTL),  making 
the  desired  changes  in  the  copy  and  using  ADDMAC  with  this  new  data  set 
and  the  original  member  name. 

A. 15  REMOVING  A PSI  xMACRO  FROM  THE  LIBRARY 

A PSI  macro  can  be  deleted  from  the  library  by  use  of  the  DELMAC 
command.  This  command  is  written  as  follows: 

DELMAC  macro-name 

where  macro-name  is  the  name  of  the  macro  to  be  removed.  DELMAC  will 
give  the  user  the  opportunity  to  specify  additional  macros  to  be  deleted 
by  promptixng  for  more  names,  thus,  allowing  several  macros  to  be  deleted 
at  once. 
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A. 16  EXERCISING  A PS I MACRO 

The  DCAS  command,  RUNPROG,  is  used  to  invoke  a PS  I macro  to 
build  and  submit  a job.  Its  form  is  as  follows: 

RUNPROG  macro-name  j keyword (value)  ... 

Here,  'macro-name'  is  the  name  of  the  PS  I macro  to  be  used  and 
' [ keyword (value ) j ...'  is  a (possibly  empty)  list  of  keyword  parameters 
and  values  as  needed  for  the  particular  run.  The  following  ten  keyword 
parameters  may  be  used  with  RUNPROG.  i 


(1) 

SOURCE 

(2) 

DATA 

(3) 

OBJECT 

. - data-set  names 

(4) 

CASEDATA 

(5) 

MATDATA 

(6) 

MADOL  j 

(7) 

XCHAR 

- character (s)  to  be  appended  to  userid  (or  jobid)  for 
use  as  a jobname 

(8) 

MDPROG 

- program  name 

(9) 

MOREPARM 

- indication  as  to  whether  more  parameter  values  are 
to  be  specified  by  the  user 

(10)  SUBMIT 

- indication  as  to  whether  the  built  job  is  to  be 
submitted-, 

The  first  eight  of  these  are  provided  merely  as  a convenience; 
they  may  be  omitted  here  even  if  it  is  desired  to  override  their  default 
values  (see  Section  A.7).  Values  supplied  for  the  data-set  names  (par- 
ameters 1-6)  can  be  specified  according  to  TSO  conventions.  RUNPROG  will 
automatically  add  the  userid  if  necessary  (that  is,  RUNPROG  will  perform 
the  DSN  function  (see  Section  A. 13)  on  supplied  data-set  names).  The 
seventh  parameter  allows  the  specification  of  a character  or  string  of 
characters  to  be  used  in  the  construction  of  a jobname  for  the  job  to  be 
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submitted.  The  jobname  will  be  the  userid  or  jobid,  if  one  has  been 
established  for  the  current  user,  followed  by  the  character (s)  of  XCHAR. 

If  the  jobname  so  formed  is  greater  than  eight  characters,  it  will  be 
truncated  to  eight.  The  eight  parameter  is  merely  some  name.  It  can  be 
given  any  value,  up  to  eight  characters  in  length. 

The  ninth  parameter  is  used  to  indicate  that  additional  par- 
ameter values  (other  than  those  given  on  the  RUNPROG  statement)  are  to  be 
provided  by  the  user.  This  can  be  done  by  specifying  MOREPARM(YES);  the 
default  value  is  NO  (see  Section  A.8).  The  tenth  parameter  indicates 
whether  or  not  the  job  being  built  is  to  be  submitted  for  batch  execution. 
The  default  value  is  YES.  If  SUBMIT(NO)  is  specified  then  RUNPROG  will 
build  and  list  a complete  job  but  will  not  submit  it.  It  will  save  the 
job  in  a data-set  named  JOB.CNTL  in  the  current  user's  library.  If 
SUBMIT ( BIST)  is  specified,  the  job  will  be  listed  and  saved  as  JOB.CNTL 
as  well  as  being  submitted. 

^ It  should  be  noted  that  RUNPROG  is  a TSO  command  procedure 

(CLIST)  and  as  such  allows  the  use  of  abbreviations  for  keyword  parameter 
names.  Only  enough  characters  need  be  specified  to  insure  the  unique 
identification  of  a given  parameter.  For  example,  one  could  write, 

RUNPROG  P1234  SO (SOURCE. FORT)  D(DATA.DATA)  0( OBJECT. DATA)  X(A) 
MO(YES)  SU(NO) 


A. 17  TESTING  A PS I MACRO 

A PS I macro  can  (and  should)  be  tested  with  the  TESTMAC  command 
before  placing  it  into  the  macro  library.  This  command  is  very  similar  to 
the  RUNPROG  command  except  for  the  following: 

(1)  It  accesses  a macro  existing  as  a data  set  in  the  library  of  the  in- 
dividual using  the  TESTMAC  command. 
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(2)  The  Job  Control  Language  (JCL)  statements  produced  by  processing  the 
macro  will  not  be  submitted  but  will  be  displayed  at  the  terminal 
as  they  are  being  built.  Prompting  messages,  if  any,  will  appear  as 
they  are  encountered  within  the  macro.  Hence  they  may  be  interspersed 
with  the  JCL  statements  being  built.  These  messages  should  be  answer- 
ed as  usual. 

The  form  of  the  TESTMAC  command  is  as  follows : 

TESTMAC  data-set-name  keyword (value)  ... 

The  'data-set-name'  specifies  the  name  of  the  data  set  containing  the 
macro  to  be  tested.  The  name  must  include  the  type  qualifier.  The  key- 
word parameters  are  specified  in  exactly  the  same  manner  as  for  the 
RUNPROG  command.  All  but  the  SUBMIT  keyword  can  be  used  with  TESTMAC. 

The  following  is  an  example  demonstrating  the  use  of  TESTMAC  to  check  a 
newly  written  macro,  created  as  a TSO  data  set  named  F2941.CNTL,  where  a 
value  for  the  keyword  DATA  and  an  indication  that  more  parameters  are  to 
) be  supplied  are  given: 

TESTMAC  P2941.CNTL  DATA (P2 941 . DATA ) MOREPARM( YES ) 

A. 18  SPECIFYING  DATA-SET  NAMES  TO  RUNPROG 

In  TSO  a user  may  refer  to  a catalogued  data-set  outside  his  own 
library  by  enclosing  the  name  in  quotes.  Unfortunately  quotes  are  also 
used  as  delimiters  in  TSO  and  PL/l  (the  language  of  RUNPROG).  This  re- 
quires that  one  often  write  two  successive  quotes  to  indicate  one  actual 
quote  character.  Several  levels  of  passing  these  characters  can  lead  to 
a proliferation  of  quotes. 

Without  going  into  the  reasons  why,  the  following  rules  are 
given  as  a guide  for  specifying  a quoted  data-set  name  to  RUNPROG. 
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(1)  When  specifying  a data-set  as  SOURCE,  OBJECT,  DATA,  CASEDATA,  '-1ATDATA, 
or  MADOL  as  part  of  the  RUNPROG  statement  or  when  specifying  such  a 
data-set  with  any  of  the  DCAS  commands,  PRUT,  PNCH,  PRNTOUT,  PRNTPDS, 
PRNTR,  PNCHR,  PRNTOUTR,  GETDS  or  FUTDS,  the  name  must  be  preceded 

by  four  (4)  quotes  and  followed  by  four  (4)  quotes. 

(2)  When  the  data-set  is  specified  as  an  additional  parameter  (using  the 
MOREPARM(YES)  option),  the  name  must  be  both  preceded  and  followed 
by  three  (3)  quotes. 

(3)  'When  prompted  for  a data-set  name,  only  single  quotes  are  required 
both  pre  eding  and  following  it. 

Data-sets  which  are  within  the  user's  library  are  specified 
identically  in  all  cases;  that  is,  the  complete  data-set  name,  exclusive 
of  the  'userid'  and  its  following  decimal  point  is  given. 

) 

A. 19  EXAMPLE  OF  A PS I MACRO 


The  following  Figure  is  an  example  of  a PS  I macro.  Card  1 is 
just  a comment.  Card  2 is  a macro  definition  statement  giving  the  macro 
the  name,  EXAMPLE,  and  establishing  default  values  for  the  parameters, 

TELE,  PRIORITY,  PROGRAM#,  and  CLASS.  Card  3 tests  the  variable,  TIME.  If 
TIME  is  not  a 2 (i.e.  a value  for  TIME  was  specified  using  the  MOREPARM(YES ) 
option)  the  statement  on  card  4 is  executed.  Hence  PRIORITY  will  be  3 if 
TIME  is  2 and  0 otherwise.  Cards  5 through  8 are  JCL  cards  in  which  par- 
ameter substitutions  will  be  made.  JOBNAME,  $USERID,  USERNAME,  $CSR#, 

$DB#,  $GP#,  and  BIN#  are  automatically  determined  based  on  the  logon  in- 
formation. The  other  parameters  get  their  values  from  the  defaults  spec- 
ified on  card  2,  from  information  given  by  the  user  with  the  MOREPARM(YES ) 
option,  or  as  determined  by  the  macro  itself  (as  possibly  for  PRIORITY). 

Card  9 is  another  comment.  Card  10  tests  the  variable,  PLOTS.  Since  PLOTS 
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is  not  a system  variable,  and  no  default  has  been  established  for  it,  the 
user  will  be  prompted  for  a value  (unless  he  has  already  supplied  one 
using  the  MORE PAR M( YES ) option).  If  the  user  supplied  value  is  'YES', 
that  is,  there  will  be  plots  produced,  cards  12  through  15  (those  between 
the  DO  statement  on  card  11  and  the  END  statement  on  card  16)  will  be  in- 
cluded in  the  job  being  built.  Otherwise,  they  will  not.  Thus,  appro- 
priate operator  instructions  and  a SETUP  card  will  be  included  if  there 
is  to  be  plot  output.  In  this  case,  the  values  for  JOBNAKE,  PRIORITY, 
USERNAME,  BINtf,  $DP^}  $GP^,  and  $CSR7,  will  be  substituted  as  before.  The 
user  will  be  prompted  for  a value  for  the  variable,  PAPER,  unless  he  gave 
one  earlier,  and  that  value  will  be  substituted  in  card  14.  Cards  18 
through  23  are  JCL  statements.  The  values,  if  any,  supplied  by  the  user 
on  the  RUNPROG  statement  for  SOURCE  and  OBJECT  will  be  substituted  in 
card  18  and  19.  If  no  values  were  given  the  system  defaults  will  be  used. 
Card  2k  is  again  a comment.  Card  25  is  another  test,  checking  to  see  if 
an  output  data  is  to  be  saved.  The  user  will  be  prompted  for  a value  for 
OUTPUT  ’unless  he  previously  gave  one,  and  the  statements  between  the  DO 
on  card  26  and  the  END  on  card  30  will  be  executed  only  if  the  value  of 
OUTPUT  is  not  'NO'.  In  that  case  its  value  will  be  taken  as  the  name  to 
be  given  the  output  data  set.  The  statement  on  card  27  performs  the  DSN 
function  on  the  name  (see  Section  A. 13),  converting  it  from  a valid  TSO 
specification  of  a data  set  name  in  an  OS  acceptable  form.  The  sub- 
stitution of  this  name  is  then  made  to.  the  DD  statement  given  on  cards 
28  and  29.  Cards  31  and  33  check  the  value  of  PLOTS  again  and  the  appro- 
priate DD  card,  either  32  or  3^  will  be  included.  Card  3?  and  36  are  JCL 
cards.  A value  will  be  substituted  for  the  variable  DATA  ir.  card  35  as 
was  specified  by  the  user  or  by  default  if  none  was  specified.  Finally 
card  37  indicates  the  end  of  the  macro. 
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APPENDIX  B 

THE  INPUT  DESCRIPTION  LANGUAGE 
B.l  INTRODUCTION 

The  ID  (input  Description)  language  is  just  an  extension  of  the 
PSI  (Program  Setup  Instructions)  language.  The  basic  rules  for  constructing 
ID  macros  are  the  same  as  for  PSI  macros,  and  all  statements  which  are  legal 
in  .SI  macros  are  legal  in  ID  macros.  The  additional  language  constructs 
for  input  description  are  given  in  the  following  sections. 

B.2  DESCRIBING  INPUT  PARAMETERS 

A character  string  giving  the  meaning  of  an  input  parameter  (or 
any  macro  variable)  can  be  associated  with  its  name  by  means  of  a DEFINE 
statement.  The  form  of  this  statement  is  as  follows: 

DEFINE  identifier  (character  string); 

where  'identifier'  is  any  variable  name 

'character  string'  is  any  string  of  characters 

For  example,  the  string  'MACH  NUMBER ' can  be  associated  with 
the  variable  name  'M'  as  follows: 

f DEFINE  M( MACH  NUMBER ) ; 

A more  involved  description  is  also  possible  as  indicated  by 
the  following  example. 

% DEFINE  PRNT( PRINT  OPTION  - 

PRNT=0  FOR  STANDARD  PRINT, 

PRNT=1  FOR  SUMMARY  PRINT  ONLY); 
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Here  the  variable,  PRNT,  is  a flag  by  which  the  user  may  specify  one  of 
two  output  options. 

Once  a parameter  has  been  so  defined  a user  may  obtain  the 
associated  description  by  typing  a '?'  followed  by  the  parameter  name. 
This  may  be  done  whenever  a response  of  some  kind  is  expected  from  the 
user.  This  action  interrupts  the  normal  processing  and,  after  providing 
the  information  requested,  execution  of  the  macro  resumes  automatically. 

B.3  DESCRIBING  INPUT  FORMATS 

In  order  to  describe  the  formats  in  which  a program  expects  its 
input  to  be  given  the  PUT  statement  has  been  expanded  to  allow  a format 
specification.  Syntactically  this  statement  resembles  the  PUT  EDIT 
statement  in  PL/ I.  It  is  written  as  follows: 

% PUT  (identifier  £, identifier ^ ...)  (format  list) 

where  'identifier'  is  any  variable  name 

’format  list'  is  any  valid  PL/ I format  list 

Upon  execution  of  this  statement  the  specified  list  is  written 
on  the  output  file  according  to  the  format  specification.  An  example  of 
this  form  of  the  PUT  statement  is  given  below. 

1o  PUT  (X, Y,Z)  (A(3),X(2),2A(5))5 
b.4  specifying  para:eter  types 

Parameters  may  be  declared  to  be  of  one  of  three  types  - 
character,  integer,  or  real.  This  is  accomplished  with  the  TYPE  state- 
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ment.  It  is  written  as  follows: 


r - uhak 

TYPE  (identifier  , identifier  ...)  INTEGER 

“ -J  DTPAT 


'identifier  .identifier 


] ...) 


CHAR 

INTEGER 

REAL 


where  'identifier'  is  any  variable  name 

For  example,  one  could  specify  X and  Y to  be  real  numbers; 

I,  J,  and  K to  be  integers;  and  ABC  to  be  a character  string  as  follows: 

°lo  TYPE  (X,Y)  REAL, (l,J,K)  INTEGER,  (ABC ) CHAR; 

When  a parameter  has  been  so  typed,  any  value  supplied  for  it 
will  be  checked  for  compliance.  If  the  value  is  not  of  the  proper  type, 
the  user  is  immediately  notified  and  prompted  for  a new  value  if  the 
macro  is  being  executed  interactively.  Otherwise,  an  error  message  is 
written  on  the  output  file. 

B.5  SPECIFYING  PARAMETER  LIMITS 

A range  or  set  of  acceptable  values  can  be  specified  for  a 
parameter  with  the  LIMIT  statement.  It  can  be  written  as  follows: 

% LIMIT  range  £,rangej  ...  ; 

where  'range'  can  be  one  of  the  following: 

identifier  = (constant  £, constant J ... ) 


identifier 


constant 
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constant 


constant 


where  'identifier'  is  any  variable  name 
'constant'  is  any  valid  constant 


With  the  LIMIT  statement  a parameter  can  be  required  to  be  one 
out  of  a set  of  values  or  to  lie  between  two  values.  Multiple  ranges  or 
sets  can  be  given  for  a single  parameter  in  which  case  they  are  logically 
OR-ed  together.  For  example,  to  specify  that  the  variable  X must  be 
either  between  0 and  1 or  the  value  -99  > one  could  write, 

% LIMIT  0 <=  X<=  1,  X = -99; 

Several  parameters  may  be  given  limits  with  the  same  statement 
as  in  the  following  example: 

io  LIMIT  0 < = I < =10,  X > 0,  A = ( 'K' , 'L'  ) 

This  statement  says  that  I must  lie  between  0 and  10  (inclusive), 
that  X must  be  greater  than  0 and  that  A must  have  either  'K'  or  'L'  as  a 
value . 
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APPENDIX  C 

"ASSIST"  SURVEY  RESULTS 

C.l  INTRODUCTION 

On  May  20,  1976  a questionnaire  was  distributed  to  all  DCAS 
users  outside  the  Administrative/Computer  Services  organization.  The 
purposes  of  the  questionnaire  were  to  evaluate  the  Program  Submittal 
(RUNFROG)  component  of  ASSIST  (A  Scientific  £oftware  Interface  System 
for  Terminal-users)  and  to  obtain  information  for  guiding  the  development 
of  additional  capabilities.  The  results  of  28  completed  questionnaires 
are  presented  and  analyzed  in  the  following  section. 

C.2  RESULTS 

^ The  first  question  attempted  to  get  an  indication  of  the  dis- 

tribution of  users  according  to  their  degree  of  activity  on  the  system. 
The  question  and  number  giving  each  response  are  given  in  Table  1.  The 
results  indicate  a fairly  even  distribution. 

Question  two  tried  to  determine  whether  users  felt  the  RUNFROG 
capability  to  be  of  help  in  their  work.  The  results  were  overwhelmingly 
affirmative.  The  primary  reasons  sighted  for  this  centered  around  the 
fact  that  RUNFROG  gave  them  a simple,  convenient  means  for  getting  a job 
submitted  and  run  quickly.  The  complete  responses  to  this  question  are 
given  in  Table  2. 

The  third  question  asked  users  to  describe  any  difficulties 
they  had  experienced  with  RUNPROG.  The  major  problems  stated  were  that 
the  RUNPROG  command  itself  was  slow  to  execute  and  that  the  documentation 
for  it  was  incomplete  or  confusing.  Table  3 contains  the  complete  set  of 
responses . 
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Please  estimate  your  activity  on  DCAS  as  follows: 


Terminal  use 


?*$)  heavy  user  (more  than  10  hours/week) 

?*$)  moderate  user  (5  - 10  hours/week) 

Ijo ) light  user  (1  - 5 hours/week) 

1%)  occasional  user  (less  than  1 hour/week) 


b)  RUNPROG  use 

4 (l hjo)  heavy  user  (more  than  20  times/week) 

9 (32^)  moderate  user  (10  - 20  times/week) 

5 (18$)  light  user  (3-10  times/week) 

10(36*$)  occasional  user  (less  than  3 times/week) 


Table  1.  DCAS  Activity 
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Do  you  feel  that  the  RUNPROG  capability  is  a benefit  in  your 
present  work? 


2k  ( 36% ) yes 

1 ( 4:/c)  no 

1 ( 4?')  yes  & no 

2 ( 7'%)  no  response 


If  so  how? 


6 (21^, 
5 (18%) 
5 (18  /0) 
3 (11%) 
2 ( Tp) 
2 ( 7/q  ) 
1 ( 4ft) 
l ( 4fl) 


it  improves  job  turnaround  time 
it  provides  faster  way  to  submit  a job 


it's  simplier  than  generating  JCL 
it's  essential 

it  allows  direct  submittal  by  user 
it's  convenient 
it ' s efficient 
it  reduces  errors 


If  not,  why  not? 


1 ( U/o)  it's  too  slow 
1 ( br', ) it’s  not  applicable 


Table  2.  Benefit  of  RUNPROG 


L.  . 
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What  difficulties  (if  any)  have  you  experienced  in  your  use 

of  RUWFROG? 


6 (2lfl) 
6 (21?)) 

2 ( T!q) 

1 

1 ( 4?,) 
1 ( 4fc) 


it 1 s too  slow 

the  options  are  confusing  (poor  documentation  and 
non-standard  keywords ) 
machine  problems 
lost  output 

hard  to  run  multiple  cases 

many  user  errors  not  caught  (e.g.  incorrect  data 
set  name) 


Table  3.  RUNPROG  Difficulties 
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Question  four  asked  users  what  changes  were  felt  to  be  necessary 
in  RUNPROG.  The  most  common  response  was  that  they  wanted  it  to  run  faster. 
The  results  of  this  question  are  given  in  Table  4. 

In  question  five  users  were  asked  to  rate  RUNPROG  by  comparing 
it  to  past  methods  of  operation.  Approximately  43%  felt  it  was  a signif- 
icant improvement  and  64%  felt  it  was  at  least  some  improvement.  Unfortu- 
nately 32%  did  not  respond  at  all,  most  of  them  indicating  they  did  not 
know  what  they  were  supposed  to  compare  RUNPROG  to.  The  intent  of  the 
question  was  to  determine  whether  users  felt  that  having  a capability  to 
submit  jobs  from  a terminal,  without  having  to  be  concerned  with  JCL,  was 
better  than  giving  instructions  to  a programmer  and  having  him  submit  the 
job.  Even  though  many  seemed  to  misunderstand  the  question,  the  responses 
from  those  who  did  clearly  indicate  a great  satisfaction  and  acceptance  of 
RUNPROG.  The  complete  responses  to  this  question  are  given  in  Table  5. 

^ Question  six  asked  users  to  express  their  opinions  regarding  the 

usefulness  of  a capability  to  obtain  information  describing  available  pro- 
grams from  the  terminal.  A majority  (54%)  of  the  users  strongly  favored 
the  addition  of  such  a capability,  and  32%  thought  it  might  be  useful.  Most 
thought  it  was  important  to  have  access  to  such  information,  but  many  felt 
on-line  access  was  not  necessary.  The  responses  are  listed  in  Table  6. 

Question  seven  asked  users  for  their  opinions  of  an  interactive 
capability  for  assisting  in  preparing  program  input.  Again  54%  felt  such  a 
capability  would  definitely  be  beneficial.  Another  21%  said  "maybe"  while 
18%  said  "no”  and  7%  did  not  respond.  Those  favoring  the  addition  of  this 
capability  thought  it  would  reduce  errors  and  make  input  preparation  easier. 
Those  responding  negatively  generally  could  not  see  how  it  would  help  them 
in  their  work.  Table  7 gives  the  complete  set  of  responses. 
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What  changes  (if  any)  would  you  like  to  see  in  the  way  RUNPROG 

operates? 


6 

(21  °fo) 

2 

( 1$) 

2 

( 7°f>) 

1 

{ H) 

1 ( 

i ( H) 


improved  response 

more  flexibility  in  overriding  JCL 

check  data  set  names  for  correctness 

be  able  to  view  JCL  and  correct  mistakes  before 

submittal 

better  terminal  availability 

be  able  to  enter  multiple  cases  at  once 

be  able  to  reuse  a data  set  without  making  a copy 


Table  4.  RUNPROG  Improvements 


What  is  your  overall  rating  of  the  RUNPROG  capability? 


12  (43^) 
6 (2lj) 

1 ( K) 
0 ( o£) 

0 ( O/,) 

9 (32fl) 


a significant  improvement  over  past  methods  of  operation 

somewhat  better  than  past  methods 

comparable  to  past  ways  of  operating 

somewhat  worse  than  past  methods 

a definite  step  backwards 

no  response 


Table  5.  RUNPROG  Rating 
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Currently  being  designed  is  an  on-line  capability  which  would 
allow  DCAS  users  to  obtain  information  describing  available  computer  pro- 
grams (i.e.,  a capability  enabling  remote  users  to  get  a list  of  program 
titles  and  optionally  abstracts  for  existing  software  in  a specified 
category).  Could  you  find  such  a capability  useful? 


15  (5H) 
6 (14%) 
9 (32b) 

Explain: 

8 (29))) 
6 (21%) 

3 (lift) 
2 ( 7%) 

1 ( 4fl) 

M W 

1 ( K) 


yes 

no 

maybe 


it  would  make  information  conveniently  available 
it's  not  necessary  to  have  an  on-line  capability;  a 
batch  capability  would  be  sufficient 
it  would  reduce  duplication  of  software  development 
it  should  not  impact  overall  DCAS  response 
it  would  increase  use  of  existing  programs 
information  must  be  kept  up-to-date 
fellow  workers  are  a better  source  of  information 


Table  6.  Information  Retrieval  Capability 
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Also  in  the  design  stage  is  an  interactive  capability  which 
would  assist  DCAS  users  in  preparing  input  data  for  program  selected  to  run 
(i.e.,  a capability  which  would  prompt  users  for  information  and  properly 
format  it  to  meet  program  input  specifications).  Would  you  find  such  a 
capability  useful? 


15 

(54 $) 

5 

(1836) 

6 

(21*) 

2 

( 7lo) 

Explain : 

5 

{l&fo} 

4 

(14$) 

3 

(11$,) 

2 

( 7$) 

2 

( H) 

2 

{ 7$) 

1 

( 4*) 

1 

( 4$) 

1 

( 

1 

( 4$) 

1 

( 4$) 

1 

( 4$) 

yes 

no 

maybe 

no  response 


it  should  not  slow  down  overall  response 
it  would  reduce  input  errors 
it  would  help  the  novice  or  occasional  user 
it  would  be  more  convenient 

EDIT  is  usually  sufficient  for  input  preparation 
no  foreseen  use 
it  would  be  more  efficient 
it  would  save  time 

it  would  be  helpful  for  FAMAS  matrices 
it  should  provide  user  with  enough  information 
it  must  be  optional 

it  would  be  impractical  for  large  amounts  of  data 


Table  7.  Input  Preparation  Capability 


) 


LOCK  HE  E D 


c-3 


LR  28005 


) 


uestion  eight  asked  users  what  other  capatilities  they  would 
like  to  see  incorporated  into  DCAS.  tost  users  wanted  capatilities 
available  under  TSO  but  not  included  in  the  TSO  subset  provided  with  DCAS. 
Users  also  indicated  they  wanted  better  response.  The  corrplete  list  of 
responses  is  given  in  Table  5. 


Finally,  question  nine  gave  users  a chance  tc  make  any  other 
comments  regarding  DCAS.  The  need  for  better  response  was  again  mentioned, 
and  a desire  to  have  DCAS  available  for  a longer  period  was  also  expressed. 
All  the  comments  given  are  listed  in  Table  9* 


C.3  CONCLUSIONS 

Based  upon  the  responses  to  the  questionnaire,  the  following 

conclusions  can  be  drawn: 

(1)  The  RUNPROG  capability  is  a highly  accepted  and  useful  tool  for  DCAS 
users  and,  therefore,  should  be  fully  developed. 

(2)  Poor  response  is  the  biggest  problem  with  RUNPROG  and  DCAS  in  general. 
Efforts  to  make  improvements  in  this  area  must  be  initiated. 

(3)  The  documentation  of  RUNPROG  and  other  DCAS  capabilities  is  inadequate 
and  should  be  improved. 

(k)  The  development  of  a capability  to  obtain  information  about  existing 
programs  from  a terminal  would  probably  be  beneficial.  It  might  be 
sufficient,  however,  to  allow  only  the  request  for  information  to  be 
made  at  the  terminal  and  have  the  actual  information  found  and  printed 
in  a batch  mode. 

(5)  The  development  of  a capability  to  assist  in  the  preparation  and  check- 
ing of  program  input  data  would  help  many  DCAS  users,  but  the  use  of 
this  capability  should  be  optional 
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•/hat  other  capabilities  would  you  like  to  see  incorporated  into 
DCAS  that  would  make  it  easier  for  you  to  use  existing  applications  software'. 


2 

( Tf>) 

2 

( 

2 

( Tf>) 

1 

{ 4 

1 

( 4%) 

1 

( H) 

1 

( bf0) 

1 

( k1°) 

1 

( W 

better  response 

foreground  execution  capability 

improved  documentation 

expanded  CLIST  capability 

all  of  the  TSC  commands 

ability  to  print  data  sets  with  c 

reduced  default  track  allocations  for  data  r-*s 

more  user  disk  space 

capability  to  store  data  at  terminals  o >aper  tape  or 
cassettes 


) 


Table  8.  DCAS  Improvements 
Additional  Comments: 


4 (14%) 

2 ( .ft) 
2 ( r%) 

1 ( 

1 


1 ( 4t) 
1 ( 4 %) 

1 ( 4/°) 
1 ( 4 j) 

L1M 

1 ( H) 


need  better  response 
need  foreground  execution  capability 
need  longer  DCAS  availability  (6A’:  to  6 " 
need  better  machine  reliability 

need  capability  to  list  contents  of  a MV.-.  lib::  try 

member 

need  capability  to  get  a list  when  punching  a :ta  set 

should  be  able  to  specify  that  punch  be  interpreted 

the  print  of  a data  set  should  start  at  the  top  of  a page 

log-on  time  should  be  reduced 

users  should  be  taught  to  read 

it’s  a useful  system 


Table  9.  Comments 
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